Languguage OS 2/Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO/language/pcpil/pidoc4.txt

Text File | 1994-02-28 | 38KB | 1,050 lines

Chapter 3. OPERATORS AND EXPRESSIONS

PILOT accepts expressions in many contexts.  An expression is a combination
of variables, numeric constants, string constants, functions and operators.
Expressions are formed in the normal manner allowed by other programming
languages.  Operator precedence is similar to that of basic.  Parentheses may
be used to group subexpressions.

EXAMPLE: simple expressions

       X + 5
       SIN(I)
       2.5
       (A + B) <= (C + D)


DATA TYPES

Each element of an expression is a number or a string value.  Numbers are
stored in floating point form with an accuracy of about 6 decimal digits.
Strings are stored in variable length form with a terminating null character.

Each operator or function expects to act on a particular type of argument,
and in return produces a particular type of result.  For example, + expects
two numeric arguments and it produces a numeric result. A unique and
convenient feature of PILOT is auto-type conversion.  This means that any
time an argument is of the wrong type (string or number) it is automatically
converted to the correct type for the context.  A number is converted to a
string in a manner like that of the STR function, which puts the value in
printable format with decimal places only if necessary.  A string is
converted to a number in a manner like that of the FLO function, which scans
the string for the first number value or returns zero if no number is found.
VARIABLES

A variable name can be up to length six.   The first character must be a
letter.  Other characters may be letters or digits.  The last character may
be a $ to signify a string variable.  Upper and lower case letters are
considered to be equal when naming a variable (i.e. - XYZ and xyz name the
same variable).  A string variable must be dimensioned in a D: statement
before it can be used to store a string value.

EXAMPLE: variables

      X  COUNT  J5  able  NAME$

SYSTEM VARIABLES

There are several system variables which can be used in the same context as
other variables.

%A - answer counter

%A is a numeric variable equal to the number of times the last A: has
executed without any other intervening A:. It tells how many attempts the
student has made on this question.

%B - answer buffer

%B is a string variable which is set to the response given by the student on
each A:. %B has a maximum length of 80 characters. It can be subscripted like
any string variable.

%E - return point of last U:

%E is a numeric variable which returns the jump value of the return point of
the most recent USE statement. It is the location which would be returned to
via an END statement.

%N %M %L - match result variables

These are parsing variables which return information about the last MATCH.
See the MATCH statement for more details.

See also:  COMPUTE, DIMENSION, SUBSCRIPTING

SUBSCRIPTING

       array  (position)
       strng$ (position)
       strng$ (position, length)

SUBSCRIPTS are used to select an individual value out of a numeric array or a
substring out of a string variable.  Subscripts consist of a position and
possibly a length, enclosed in parentheses after a variable name. The
position and length values can be expressions. Before subscripts can be used
the variable must have been dimensioned.  See the DIMENSION statement for
more information.

NUMERIC ARRAY SUBSCRIPTING

Numeric arrays start at subscript zero and end at the dimensioned size.  An
attempt to subscript beyond the array limit results in an error message. A
reference to an array name without subscripts results in a reference to item
number zero of the array.

EXAMPLE 1: array subscripts

       C: A(3) = X
       C: A(I) = A(I) + 1
       C: LIST(J) = A * 5

STRING SUBSCRIPTING

String subscripts start at one. If you specify a starting position less than
one, PILOT will assume you meant one. If you omit the length, a length of one
is assumed. The portion of a string picked out by subscripts is sometimes
called a substring.


EXAMPLE 2: simple string subscripts

       D: X$(20), Y$(10)
       C: X$ = "ABCDEFGHIJKLMNOP"
       C: Y$ = X$(3)
                          Y$ is now equal to "C"
       C: Y$ = X$(5,4)
                          Y$ is now equal to "EFGH"

You can assign a value into a substring by placing the subscripted string
variable on the left hand side of a COMPUTE statement. In this case, only the
characters within the substring are modified. All other characters within the
string are unchanged.

EXAMPLE 3: assignment to a substring

       D: X$(20)
       C: X$ = "ABCDEFGH"
       C: X$(3) = "s"
                          X$ is now equal to "ABsDEFGH"
       C: X$(4,3) = "12345"
                          X$ is now equal to "ABs123GH"
       C: X$(4,3) = "xy"
                          X$ is now equal to "ABsxy GH"

Since a string variable can contain a variable number of characters at any
one time, it is possible that its current length is less than its maximum
length as set up by the DIMENSION statement.

If, when a subscripted string is not the target of a COMPUTE statement, the
start subscript is over the end of the current string length, the returned
value is a null string. If the start subscript is within the string but the
length would run over the string length then only the remaining characters
are returned.


EXAMPLE 4: padding a string to its max length

       D: X$(100)
       C: X$(100) = " "
                          X$ is now equal to 100 spaces


You can access a substring of any length you wish. If you leave off the
length, then the substring is assumed to be length 1. If you give a length
that would go past the current end of the string, then the substring goes
from the starting position you specified to the current end of the string. So
by using a large length value you can reference a substring starting at a
given position and containing the rest of the string. This is similar to the
RIGHT function in some languages.

EXAMPLE 5: the rest of the string

       C: X$ = "ABCDEFGHIJ"
       C: Y$ = X$(3,20)
                          Y$ is now equal to "CDEFGHIJ"

See also:  DIMENSION, VARIABLES

NUMERIC CONSTANTS

       [-]digits
       [-]digits.digits

A numeric constant consists of an optional leading minus sign, a string of
decimal digits optionally including a decimal point. Numbers are retained to
about six digits of accuracy.

EXAMPLE: numeric constants

       5
       63.789
       -42.1

STRING CONSTANTS

       "text"

A string constant, or literal, consists of zero or more characters enclosed
in quotes.

EXAMPLE:

       A$="BANANA"
       T(X$ < "A"): NO SIR.

OPERATORS


ARITHMETIC

       x + y       x - y       x * y       x / y
       x % y  (remainder of x/y)        -x

To compute A to the B power use EXP(B*LNE(A))


RELATIONAL

       x < y     x > y     x = y     x <> y
       x <= y    x >= y

Comparison is numeric if x is a number or string if x is a string.  For
string comparisons the shorter string is padded on the right with spaces for
comparison purposes.  Relational operators always yield a one for true or a
zero for false.


LOGICAL

       x & y         (true if both x and y are non-zero)
       x ! y          (true if either x or y is non-zero)
       ^x or ~x     (true if x is zero)

Logical operators always produce a 1 for true or a zero for false.


STRING

       x$ !! y$       (concatenation)

Concatenation produces a string consisting of the string value of y$ appended
to the right end of the string value of x$.  FUNCTIONS


A built-in function can be used in an expression to return a pre-defined
computation or value.  The function name is always followed by parentheses
containing one or more function arguments. The function arguments may be
expressions.

ABS(X) - the positive value of X ABS(9) is 9, ABS(-9) is 9

ASC(X$) - the numeric value 0-255 of char X$, ASC("A")=65

ATN(X) - arctangent in degrees of X, ATN(1) is 45

AUX(0) - reads the com1: (rs232) port

Returns CHR(0) if no byte ready to read, or a character from CHR(1) to
CHR(255).The com1: port must be set up via a DOS MODE command before entering
PILOT.

CAP(X$) - the upper case value of string X$

CAP("X2 is it.") is "X2 IS IT".

COS(X) - cosine of X degrees, COS(60) is .5

CHR(X) - the Xth ascii character, CHR(65) is A

CLK(n) - time and date clock

n=0 gives the time of day in seconds, n=1 gives year; n=2 gives month; n=3
gives day

DEC(X,n) - string value of number X with n decimal places

DEC(13.45095,2) is 13.45

EXP(X) - e to the X power,  EXP(3.5) is 33.11 ...

FIZ(X$) - size of a file

X$ MUST BE a string variable, NOT an expression. The variable contains a path
or file name. The return value is the length, in bytes, of the file, or -1 if
the  file does not exist.

FLO(X$) - convert a string to a real number

The numeric value of the first number found in string X$, FLO("Either 12 or
14") is 12.

INS(X$) - search for a character in %b

Returns zero if character X$ is not in %B, otherwise the first
position in %B where X$ is found.

INP(X) - machine level IN instruction

Returns a byte from io port X.

INT(X) - value of X truncated to an integer, INT(13.89) is 13

KEY(X) - return keyboard status

Returns zero if no key is pressed,  otherwise the ascii code for the
depressed key.  If X=0, then the character is read from the type-ahead
buffer.  If X=1, then the character is left in the type ahead buffer.

LEN(X$) - current length of string X$, LEN("abc") is 3

LNE(X) - natural log (base e) of X, LNE(10) is 2.302 ...

LOG(X) - log base 10 of X, LOG(10) is 1.00

MEM(0) - number of unused bytes for strings and arrays

MOD(0) - returns the current screen mode

OFF(X$) - memory offset address

Returns the offset part of the address of the string variable.

PEK(X) - read memory byte

Returns a value from 0 to 255 equal to the byte in memory at offset X in the
segment whose base is in the variable %A.  RND(X) - random number generator

If X is zero, returns a random   fraction from 0 to 1. If X>0, returns a
random integer from 0 to X-1. If X=-1, a fixed sequence of random numbers is
used for all subsequent uses of RND and SFL.

RSP(X$) - the string value of X$ with all spaces removed,

RSP("That is all") is "Thatisall".

SEG(X$) - memory segment address

Returns the segment part of the address of the string variable.

SFL(X$) - shuffled version of the characters in string X$,

SFL("abcde") might be "bcade".

SGN(X) - -1 if X is negative, 0 if X is 0, +1 if X is positive

SIN(X) - sine of X degrees, SIN(30) is .5

SPC(n) - gives n spaces

SQR(X) - square root of X, SQR(9) is 3

STR(X) - the string value of number X

SWP("xy") - swap characters

Returns a string equal to the value of %B except that each character x is
changed to character y; if %B holds "Why not exit?", SWP("xy") is Why not
eyit?

TIM(0) - response time in seconds of last A:

TSP(X$) - string value of X$ with trailing spaces removed

WRD(X$,n) - gives the nth word in the string X$

WRD("one two three four",2) returns "two"

XCR(0) - x position of the text cursor

XPX(0) - x position of the graphic turtle

YCR(0) - y position of the text cursor

YPX(0) - y position of the graphic turtle

EXAMPLE 1: use AUX to read N characters from serial port

       D:X$(80)
       C:X$ = ""
       C:N=10
       *LOOP  C:X$= X$ !! AUX(0)
       J(LEN(X$)<N):LOOP

EXAMPLE 2: use CLK to print date and time of day

       C: T = CLK(0)
       C: HH = INT(T/3600)
       C: MM = INT((T-3600*HH)/60)
       C: SS = INT(T-HH*3600 - MM*60)
       C: YY = CLK(1) ; MO = CLK(2) ; DD = CLK(3)
       T: #YY/#MO/#DD   #HH:#MM:#SS

EXAMPLE 3: use SFL to randomize a list of 10 questions

       D: X$(10)
       C: X$ = "ABCDEFGHIJ"
       C: X$ = SFL(X$)
       C: N=0
       R: each problem ends by a JUMP to LOOP
       *LOOP
       C: N=N+1
       J(N>10):DONE
       X: "J:QUES" !! X$(N)
       . . .
       *QUESA . . .
       . . .
       J:LOOP


Chapter 4. GOTO AND ESCAPE COMMANDS

GOTO COMMAND

The GOTO command can be enabled or disabled by an option on the PROBLEM
statement. If enabled, then each ACCEPT statement automatically checks the
student response for the command:

       GOTO destination

If present, a JUMP to the destination is immediately performed. The
destination can be any of those available on the JUMP statement.  This
feature is extremely useful when writing or debugging a long program. You can
enable the GOTO option, then when testing, you can jump around in the program
to test the relevant section. Once the program is debugged, you can disable
the GOTO command.

You could conceivably allow the student to use GOTO to navigate within a
program, however, there is a better way to give the student the branching
control needed.


ESCAPE COMMAND

The ESCAPE command can be enabled or disabled by two options on the PROBLEM
statement, the E option enables the ESCAPE key, and the F option enables the
FUNCTION and CURSOR keys. You can choose to have either, both or neither
option enabled. The enabled keys become "HOT KEYS" that cause an immediate
action to take place if the student presses the key while responding to an
ACCEPT. If one of the (enabled) hot keys is detected the automatic action is
equivalent to:

       U: SYSX

That is, the subroutine named *SYSX is called.  It is up to you to insure
that the label *SYSX is present in the program module and that it contains
the code to perform the desired special action.

The SYSX routine can be used to record comments from the student as shown in
the first example below.  It can also be used to allow the display of a menu
or glossary on demand.  The SYSX routine should end with an END statement.
If no argument is given on the END then a return is made to the statement
after the ACCEPT.  The first example below returns to re-execute the ACCEPT.
Note also that since the END can specify a label, it is not necessary to
return at all, as shown in the second example.


EXAMPLE 1: SYSX used to record student comments. If the student enters a
comment, then the ESCAPE key, the comment is written to the KEEP file.

       *SYSX  K:%B
       E:@A

EXAMPLE 2: SYSX used to return to a main menu

       *SYSX  T: GOING TO MAIN MENU.
       E:MENU

EXAMPLE 3: SYSX used to display a help page, then return to allow the student
to answer again.

       *SYSX
       GSX:                            (save screen image)
       U:HELP                        (go display the help)
       T:Push a key to go on.
       W:30000                       (pause while he reads)
       GX:                             (put the screen back)
       E:@A                           (return to ACCEPT)

ANSWER BUFFER DURING AN ESCAPE

When the SYSX routine is reached, the last character in the answer buffer,
%B, is the character that caused the escape function to take place. If the
student had entered any data prior to pushing the hot key, then that data is
also in %B, as usual. This example shows how to separate the last character
from %B.

EXAMPLE 4: SYSX used detect which hot key used

       *SYSX
       C: L = LEN(%B)                        (length of %B)
       C: K = ASC(%B(L))                   (K is hot key value)
       C(L>1): %B = %B(1,L-1)           (remove last char)


CHANGING THE ESCAPE KEYS

The P:E option enables the ESC key. It generates ASCII code 27. If you wish
to use another key for this purpose use the NX: statement to change which key
generates code 27.

Similarly, P:F enables codes 187 through 221.  These are the codes normally
generated by the function keys, the shifted function keys, and the keys in
the cursor control pad area. You could re-assign various keys in and out of
this range to control which keys are hot keys.

COMPATIBILITY

For compatibility with other versions of PILOT.  The P:E option also enables
the escape to *SYSX if the first character of a student reply is the "@"
character. This check takes place only after the student has pushed the ENTER
key to end the response.

See also:  PROBLEM, ACCEPT, USE, END

Chapter 5. ERROR MESSAGES

PILOT is programming-error tolerant. If an error is detected, the statement
in error is displayed. Before it is a message which identifies the problem.
Execution then pauses.  The user can push ctrl-c to stop the program or push
any other key to ignore the error and continue execution with the next
statement.  If it is at all possible to go on, and it usually is, PILOT will
continue with the program.  The following error codes are used by PILOT.
Error messages can be suppressed by setting the I option on the PROBLEM
statement.

disk - i/o error in program file

This usually means that the diskette has unreadable data on it.

exp - invalid or missing expression

This error can signify any number of syntax errors in the construction of a
PILOT statement. Usually it means that you have used operators or functions
improperly.

file - no file open or disk i/o error

This error can mean that a diskette is write-protected, full, or the
directory is full. It can also mean that the FILES=n parameter in your
CONFIG.SYS file specifies too few files for your system. Try placing
FILES=16  in your file CONFIG.SYS.

label - missing destination

A syntax error in specifying a jump label.

link - program file not found (program stops)

You linked to a file or path name that could not be found.

lspace - too many labels in one program module

One program module can contain 200 labels. Break the module into several
smaller ones.  mode - graphics done when not in mode 4, 5 or 6. The hardware
will not do graphics in a text mode.

open - can not open disk file

Disk drive not ready, write protected, or full. See also "file" above

opcode - invalid op code or modifiers

PILOT does not recognize what comes before the colon as a legal statement.

paren - missing parenthesis

quote - missing closing quote

sprite - illegal sprite syntax

Attempt to use a string less than 2218 bytes as a sprite table, or invalid
sprite usage.

sspace - memory overflow

Not enough string and array space left to do string operations.

subscript - too  big for the array

syntax - statement has bad command or operator

uspace - use call level is too deep ( over 32 )

var - missing variable name

vspace - over 200 variables in use

xspace - no more memory for arrays or strings


Chapter 6. DISTRIBUTING PROGRAMS

If you develop a program using PILOT and wish to provide that program to
others who may not have PILOT, you can do so by following these procedures.

First, develop and test your program in the normal way.  Next, use the PCRYPT
program to translate your lesson files into a binary format which is not
human-readable.  To do this type

       PCRYPT  name  n

n is a number which represents the maximum program length in 8KB increments.
If n is omitted, PCRYPT defaults to a value of 4 (32 KB).  This command reads
your program from file name.PIL and produces a file named name.PIX.  It is
impossible to go backwards from a PIX file to a PIL file, so be sure to keep
the original.  If your lesson uses LINK statements you must use PCRYPT to
translate all applicable lesson files. The following command can be used to
encrypt all PIL files in the current disk or directory:

       PCRYPT  *  n

To run the encrypted (.PIX) version of a program use:

       CPI  name  n

To distribute your program provide the PIX files and the file CPI.EXE to the
user.  The user can run the program but can neither read nor modify your
source code.

Do not duplicate or distribute copies of any other files provided with the
PILOT system.


Chapter 7. EZ EDITOR

EZ is a full screen text editor.  You can use it to create and edit your
PILOT programs. To use it enter:

       EZ  name.PIL

where name.PIL is the file name you wish to create or modify.  If the file
does not exist, it is created.  If it does exist, it is read into memory and
displayed on the screen.  When you finish with EZ, a backup copy of the file
is retained as name.BAK. You always have two copies of your program file:
name.PIL is the current copy and name.BAK is the file just prior to the last
time you edited the file. The EZ command and file name may be preceded by
optional drive or path designations per normal DOS conventions. The maximum
size text file supported by EZ is 50,000 bytes.


EZ FUNCTION KEYS

Once in EZ, the screen is a window on the text file.  The various cursor and
function keys are used to move around in the text and to add, change or
delete text.  When adding or replacing text, you just type on the keyboard;
what you see on the screen is what you get in the text file.  The following
summary shows the various keyboard functions you can use. The F9 key may be
used at any time to display an on-line help menu which summarizes these
functions.


Arrows - move the cursor one space in any direction

TAB - skip to next tab stop. Tab stops are each 10 columns

HOME - move to the first text line of the file

END - move to the last text line of the file

PG UP - move up (backwards) one screen

PG DN - move down (forward) one screen
INS - insert a space into the line

DEL - remove the current character

F1 - insert line

When in column 1: Insert a blank line.  When not in column 1: Split line into
two lines.

F2 - delete line

When in column 1: Remove the current line and place it on the PICK STACK.
When at end of a line: join the next line to the current line.

F3 - copy the current line onto the PICK STACK

F4 - insert top line off the PICK STACK before current line

F5 - search string, or goto a line number,  see below

shift F5 - replace search string, see below

F6 - shift to extended character set for next key pressed

shift F6 - shift lock to extended character set

Shift until F6 pushed again or the ENTER key is pushed.  This enables  the
insertion of characters from 128-255 into a program file.  See appendix B for
available characters.

F7 - expand a MACRO into the text

shift F7 - insert a file into the text

Enter the name of a file to be copied into the current file and inserted
prior to the current line.

F8 - switches to/from graphics mode

In graphics mode characters defined by N: statements in this program  file
are displayed.  User can enter name of another PILOT file which has further
N: statements to be executed.

shift F8 - enter character editor (only in graphics mode)

F9 - on-line HELP key

shift F9 - write or print all or part of text

Write all or a part of the text to a disk file or to the printer. To send the
text to the system printer enter PRN: as the file name.

To start the write at a line other than the first line of the file, place a
line containing only [[[[ prior to the first line to be written. To stop
writing prior to the end of the file place a line containing only ]]]] after
the last line to be written.

F10 - save file and exit to DOS

shift-F10 - abandon edited file, exit to DOS without saving

USING THE PICK STACK IN EZ

The PICK STACK is an invisible last-in/first-out buffer which can store up to
16 lines of text at a time.  It has three uses.

First, if you accidentally delete some lines using F2, they can be put back
again by pushing F4.

Second, to move lines push F2 once per line to delete them, then move to the
desired location and push F4 once per line to re-insert them in the new
place.

Third, to duplicate lines push F3 once per line to copy them onto the PICK
STACK, then move to the new location and push F4 once per line to insert them
in the new place.

SEARCH AND REPLACE

To search for a line number push F5 then press the "@" key, the line number,
and ENTER.

To search for a string push F5 then type the string and push ENTER. To find
the same string again just push F5 then ENTER, you do not need to type the
search string again if it is the same as the last search.

To search for a string and replace it with another string: push F5, then type
the search string (but don't push ENTER yet). Next push shift-F5, then type
the replacement string and push ENTER. EZ will find and display the next
occurrence of the search string.  At that time push shift-F5 to replace the
string, or just push F5 to find the next occurrence. By using F5 and shift-F5
alternately you can see each occurrence of the search string to decide
whether it should be replaced.

To find each successive occurrence of the search string and immediately
replace it with the replacement string, just push shift-F5.  repeatedly, once
for each time you wish to search and replace.

MACROS IN EZ

The F7 key is used to read and expand a macro into the text. A macro is a
pre-programmed sequence of instructions which can be accessed as a whole to
reduce your programming time. To include a macro push F7 then type the name
of the macro file and push ENTER. The macro may prompt for information on the
bottom two lines of the screen prior to completing the macro expansion. More
information on macros can be found below. See "How to Write a Macro for EZ".

EXTENDED CHARACTERS IN EZ

The extended characters, from ASCII 128 to 255, do not have keys on the
keyboard. By using the F6 key you can enter these extended characters.  To
enter one, push F6, then another key. A value of 128 is added to the normal
value of the key, which produces a character in the extended range. Appendix
A contains a list of the numeric values for the various keyboard
combinations.  The character editor, described below, can also be used to
determine the key combination for any particular extended character.

When EZ is entered, the screen is in text mode.  In this mode you see the
text mode extended characters for codes 128 to 255. These are the characters
built-in to the hardware which would appear in a PILOT program for text modes
(0-3).

The F8 key switches EZ to graphics mode. In this mode you see the user-
defined characters for codes 128 to 255.

The PILOT N: statement allows you to redefine character patterns to be
displayed when the PILOT program in executed. The F8 key allows you to see
the re-defined characters while editing your program with EZ.

When F8 is pushed, all N: statements in the file are executed, just as they
will be executed when the PILOT program is run. Also, you are prompted for
the name of another file which contains N: statements you wish to  execute.
This allows you to see re-defined characters even if the character
definitions are in a file other than the one in which you are editing.  When
entering the file name, you must enter the entire name (eg. PART7.PIL). If
you do not wish to enter another file name, just push ENTER.

CHARACTER EDITOR

To simplify the task of creating your own special characters EZ contains the
Character Editor.

Special characters should not be confused with character "fonts". Special
characters are limited to the standard 8 by 8 pixel character grid. Character
fonts are used to display characters of smaller or larger proportions.
Creation of fonts is documented in the section entitled "Font Editor".

To enter the character editor hold SHIFT and push F8.  The character editor
is available only after you have used the F8 key to switch EZ from text to
graphics mode. With the character editor you can:

1) See the 128 character patterns which makes up the extended character set.

2) Look up the key combination needed to enter any particular extended
character into your program file.

3) Modify one or more extended character patterns.

4) Create new extended characters.

In PILOT you re-define a character grid by specifying 64 dots and slash
characters on a NEW CHARACTER statement. The character editor lets you see
the character grid in a normal size and in a blown-up size, so that you can
see and change each dot individually. When you are done editing a character
with the character editor, the character editor creates the appropriate NEW
CHARACTER statement and inserts it into your program text for you.

Once you enter the character editor, the on-screen help menus provide all the
information you need in order to use it effectively.

CHARACTER EDITOR MODES

The character editor has two operating modes: GRID MODE and SELECT MODE. In
GRID MODE you can edit the dot pattern for a selected character.  In SELECT
MODE you can pick out which character you wish to work on.  To enter the
character editor in GRID MODE, push the SHIFT-F8 when the cursor is on an N:
statement. The character represented on the N: statement is automatically
selected for editing.

To enter the character editor in SELECT mode push the
SHIFT-F8 when the cursor is not on an N: statement.

In either mode you see the entire 128 characters displayed in the upper right
part of the screen.  The characters are displayed as they are currently
defined by the N: statements in the current file and those in any extra file
you named when you pushed F8 to enter graphics mode.

To the left you see the currently selected character in a blown-up form and
in normal size displayed in colors 1, 2 and 3. Also shown is the key
combination you use after F6 to enter this character into your text file and
the numeric value of the character, from 128 to 255.

If you are using extended characters the SELECT MODE is an easy way to look
up the keys you should press to enter any extended character into your text.
To do this push SHIFT-F8, position the cursor to the desired character, note
the F6 key combination shown, then push F10 to go back to text editing mode.

SELECT MODE

In SELECT MODE you can use the arrow keys to select the desired character.
Then push F9, to go to GRID MODE, to edit the character or push F10 to return
to text editing mode.

In SELECT MODE you can copy one character pattern to another as follows:
First move to the character to be copied, push F3 to pick up the character,
then move to the destination character and push F4 to copy it.  Notice that
to the left of the character table is the character you have currently picked
up.

GRID MODE

In GRID MODE you use the arrow keys to move the cursor around within the
blown-up character cell. You can use the various function keys to modify the
character pattern as you wish.  Note that the starting grid is saved in the
"picked up" character spot. If you accidentally destroy the character grid as
you edit, you can put it back by pushing F4. You can pick up the current grid
at any time by pushing F3 again.

Once you have finished with the character, you can push either F9 or F10. In
either case, the character editor changes or inserts the appropriate N:
statement in your text file. If you push F9, then you are moved to SELECT
MODE to select another character for editing. If you push F10 you are
returned to text edit mode.

GRID MODE FUNCTION KEYS

Arrows - move cursor 1 space in any direction (if stream mode is on, then set
or clear the dot)

F1 - turn dot on and turn off stream modes

F2 - turn dot off and turn off stream modes

shift F1 - toggle stream set mode

shift F2 - toggle stream clear mode

F3 - pick up grid and save it

F4 - restore grid to last picked up value

F5 - invert all dots in the grid

shift F5 - clear grid (turn all dots off)

F6 - rotate grid clockwise 90 degrees

shift F6 - reflect grid across a vertical center

F7 - roll grid one bit to the left

F8 - roll grid one bit up

F9 - save N: statement and goto SELECT mode

F10 - save N: statement and goto text editor

HOW TO WRITE A MACRO FOR EZ

The user of EZ can call upon pre-made code sequences which are included in
the user program by use of the F7 function key. A pre-made code sequence is
called a MACRO and is stored as a text file. By convention, PILOT language
macros are named with a file suffix of ".PIM". Usually a macro is used to
include the code in a program to perform some well-defined task. Such a task
might be to display a menu, ask a multiple choice question, or update a
student score record.

The program author can save much time by using a macro rather than taking the
time to write a commonly used code sequence over and over. Often the macro
has been written ahead of time by another party, but the author might create
personally useful macros also.

The following code could be stored in a file ANIMATE.PIM and used to move the
word "Hello" across the screen.

       TS:G10,10
       TS:*20(A Hello;D3;Wr)

To use it the author would push F7, type the name ANIMATE.PIM, and the above
two lines would be copied into the current program file.

SYMBOLIC PARAMETERS IN A MACRO

Very often the desired code sequence needs to be expanded in slightly
different ways depending on the exact needs of the program. For this reason a
macro can be written such that symbolic parameters can be filled in by the
user each time the macro is expanded. For example, assume that the above
macro should permit the author to determine what word is moved across the
screen. The file ANIMATE.PIM could be modified as follows:

       TS:G10,10
       TS:*20(A ?a;D3;Wr)

Now, when the author calls upon the macro, EZ prompts the author for the
value to be substituted in where the symbolic parameter "?a" is found. If the
author replies "happy", then the code that is expanded into the author's text
is:

       TS:G10,10
       TS:*20(A happy;D3;Wr)

The same technique could be used for the starting position, number of steps
to take and delay time:

       TS:G?a,?b
       TS:*?c(A ?d;D?e;Wr)

Now when the author calls upon the macro, EZ prompts for five symbolic
parameters: ?a, ?b, ?c, ?d and ?e.

One macro can use up to 20 different symbolic parameters, named ?a through
?u. Upper and lower case letters can be used and are considered equal. When
expanding the macro into the text, EZ prompts for the string to be
substituted for each symbolic parameter on the first occurrence of the
parameter. Then the string is substituted for all occurrences of the symbolic
parameter within the macro.

?SET COMMAND

A macro can also set the value of a symbolic parameter directly by inclusion
of a ?SET command line. The ?SET command line is not ever present in the
resultant expanded text. The function of the ?SET command is only to set the
value of a symbolic parameter. The format of the ?SET command is as follows:

       ?SET a=value

"a" represents one of the symbolic parameters,"a" through "u". The value
string is assigned to the symbolic parameters.

LABEL SYMBOLIC PARAMETER

There is one special symbolic parameter, signified by four question marks, as
shown in this example:

       *A???? T:#N
       C:N=N+1
       J(N<10):A????

EZ substitutes a unique four digit number for the ????. It is unique in that
prior to expanding the macro, that number is not present anywhere in the
text. Once the four digit number is selected, it is substituted for each
occurrence of the ???? in this expansion of the macro. If the same macro is
expanded again, then a new four-digit number is used. In this way a macro can
contain labels which are guaranteed to be unique for each occurrence of the
macro.

?REM COMMAND

It is possible to insert remarks or instructions to the user within a macro
using the "?REM" command. For example:

       TS:G10,10
       ?REM Enter the word to animate.
       TS:*20(A ?a;D2;WR)

In the above case, the user would see the message "Enter the word to
animate." just prior to the prompt for the symbolic parameter "?a". This
could be used to inform the user of the macro as to the expected values to be
filled in. The ?REM line is not included in the macro output.

CONDITIONAL MACRO EXPANSION

There are several macro commands which can be inserted in a macro to control
how it is expanded. It is possible to conditionally include or skip sections
of code via the setting of the "expand flag". When the expand flag is on then
text lines are included in the result, when the expand flag is off then text
lines are skipped. The macro commands which can affect the setting of the
expand flag are shown below. Each command must start at the beginning of a
line. The keyword may be upper or lower case. The command line itself is not
placed in the resultant expanded code.

The conditional macro statements are show below.

?ON

turn on the expand flag

?OFF

turn off the expand flag

?ELSE

invert the setting of the expand flag

?ASK question text

The question text is presented to the user. If the user responds by pushing
the "Y" key then the expand flag is turned on. Otherwise it is turned off.

?IF a=value

"a" represents one of the symbolic parameters, "a" through "u". If the
symbolic parameter matches the value string, then the expand flag is turned
on. Otherwise it is turned off.